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Abstract 

Zgoubi is a code which can be used to model accelerators and beam 
lines, comprised of magnetic and electrostatic elements. It has been 
extensively developed since the mid-1980s to include circular accelera- 
tors and related beam physics. It has been made freely available by its 
author on a code development site, including a Users' Guide, a data 
treatment/graphic interfacing tool, and many examples [l]. 
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1 Getting started 



1.1 Introduction to Zgoubi 

Zgoubi began in the early 1970s as a code to be used for ray-tracing in large 
spectrometers for nuclear physics. Since then Zgoubi has been adapted such 
that it can be used to design beam optics and beam lines, and to simulate 
nonlinear dynamics. From the mid-1980's on, it has been developed and 
used extensively for the simulation of circular accelerators and storage rings, 
and related beam physics as spin dynamics, synchrotron radiation, short- 
lived beams, etc. It has been made freely available by its author on a 
code development site, including a Users' Guide, a data treatment/graphic 
interface program, zpop, and many examples [l}j4]. 

The code is written in FORTRAN but users have developed additional 
interfaces for data handling and visualisation. In this guide reference will 
be made to MATLAB [5] scripts written for this purpose. 

In the Zgoubi code, particle trajectories in electromagnetic fields are cal- 
culated through numerical integration of the Lorentz equations. As a result 
of the efficiency of the integration (through a Taylor-series based expansion) 
and the nature of the programming language used the computation time is 
very fast. The main program array is a linear description of the Zgoubi input 
file, named zgoubi.dat. This file contains a linear definition of the lattice 
and beam parameters, and is written for the specific simulation required. 



1.2 Installation of zgoubi 

Zgoubi can be run on Windows or UNIX systems. However the post- 
processing program, zpop, requires an xterm window so is better suited 
to a UNIX system. On most Windows systems it is possible to run a UNIX 
system such as Scientific Linux (https://www.scientificlinux.org/) us- 



ing a product such as VirtualBox (https://www.virtualbox.org/), both 



of which are freely available. During the installation of Scientific Linux it 
is possible to select the developer options which should include the required 
FORTRAN compilers needed for Zgoubi. 

The installation of Zgoubi on Windows and UNIX systems is covered in 
the following section. It is also possible to install Zgoubi through installation 



of PyZgoubi (see section 1.6) [6j. It is recommended that the new user gains 
some experience with Zgoubi to gain some understanding of how the code 
works before expanding to Zgoubi interfaces such as PyZgoubi. 



1.2.1 Required Software 

To use Zgoubi you will need a FORTRAN compiler on your machine. Many 
UNIX systems will already have a compiler installed. On a Windows ma- 
chine MinGW can be used [7] . 
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To install MinGW; 



1. Visit http://www.mingw.org/wiki/Getting_Started, 

2. Click on 'mingw-get-inst', download and run the latest .exe version 



(figure la) to install to a directory of your choice, for example C:\MinGW. 



Ensure to select the FORTRAN option during the install process (fig- 
ure lb). Further information about this install is available on the 



'Getting Started' webpage above. 



X ■/ Norton- # _] Safe Web- [J Share- Vault Open - g Login AssEtant- 

X Qj Stumble |l, I like it! I All I Q Info I g ., Favorites _, Stumblers I Took-- 



sdurcefcirge 



Browse Enterprise Blog Help 



SOLUTION CENTERS Go Parallel Smarter IT Newsletters 



Home. Browse Development Euild Tools MinGW - Minimalist GNU for Windows Support 

MinGW - Minimalist GNU for Windows 

A native Windows port of the GNU Compiler Collection (GCC) 

Brought to you by: csfcrauss, cwilsol 1, eamie, keith marshal:! 
Summary Files Reviews Support News Wiki Mailing Lists Tickets * Git T 



Leaking for trie latest version? Download mirigw-6et-ir.5t-20120426.exB (662.7 KB) 



Home I Installer / mingw-get-inst 
Name * 

+ Parent folder 



/In stdler/mingw-get-intf/mmgw-get-irist- 20120426/ 
mingw-get-in5t-20120426.exe. released on 2012-04-27 
02:48:55 UTC 



[ httpi/./s ou reef org e.neVprojeEWmingw/filrr^^ 



(a) The MinGW download file. 




/Jj Setup - MinGW-Get 



Select Com pon ents 

Choose which optional components of MinGW to install [the C compiler is always 
installed} 



H MinGW Compiler Suite 
_/] C Compiler 
[7] C++ Compiler 
_7] Fortran Compiler 

ObjC Compiler 
I I Ada Compiler 

|Vl MinGW Developer ToolKlt 



:-:* -e; '■■'S''^ E=; : S- ; ;;e- 



| < Back I I Next > | Cancel 

(b) Selecting MinGW install options. 
Figure 1: Installing MinGW. 
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I « OS(C) ► MinGW \ bin 



▼ +^ M Search bin 



File Edit View Tools Help 
Organize T § Open Burn 



s 

I 



Name 

III3TOOI 



l_, libtoolize 

rningw32-c+ + .exe 
kl mingw32-cc.exe 
kl mingw32-g + + ,exe 
k"'l rningw32-g + + -4.6.2.exe 
kl mingw32-gcc.exe 
kl mingw32-gcc-4.fj,2,exe 
k"'l mingw32-gfortran.exe 



Date modified 

25/09/2010 8:16 PM 
02/12/201112:31 ... 
02/12/201112:31 ... 
02,12/201112:31 ,,, 
02/12/201112:31 ... 
02/12/201112:31 ... 
02/12/201112:31 ,„ 
02/12/2011 12:31 ... 



Type 



File 



Application 
Application 
Application 
Application 
Application 
Application 
Application 





22/01/20119:39 PM 


Application 


kl rni.ngw-get.ene 


25/04/20127:31 PM 


Application 


l^i mingwmlO.dll 


23/08/201111:59 ... 


Application extens... 



mingw32-make.exe Date modified: 22/01/2011 9:39 PM 
Application Size; 152 KB 



Figure 2: Renaming to 'make.exe'. 



3. In the subfolder 'MinGW\bin' rename the file 'mingw32-make.exe' to 
'make.exe' (figure [2]). 

4. Set the environmental variable with the address of the MinGW\bin 



directory (see section 1.2.2). 
To install Zgoubi; 
• Windows 

1. Download Zgoubi from source, e.g. |http : //sourcefo rge . net/ 
projects/zgoubi/ and unpack to a directory of your choosing, 
e.g. C:\zgoubi-5. 1.0. Version 5.1.0 is stable but newer versions 
are available. 

2. To use Zgoubi in Windows; in the main directory of the unpacked 
folder and every subfolder edit the 'Makefile' to replace every 



occurrence of ';' with '&' (figure 3b): in UNIX the semicolon 
can be used separate two lines of command, but in Windows the 
ampersand performs this function. 

Set the environmental variable with the address of the file 'zgoubi.exe' 



(see section 1.2.2 ). 



Open a command prompt (cmd.exe) in the Zgoubi folder and 
type the command make. This should trigger an install of the 
program (see figure [4]). In Windows the install is likely to com- 
plete with error messages for the install of 'zpop'. This graphics 
package needs to be run in an xterm window, which requires an 
XI 1 environment. This is not a trivial process for most Windows 
systems so it will not be covered here. 
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. V zgouhi-5.1.0 
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Organize ■> 



i ( Open Burn Newfolder 



Name 


Date modified 


Type 


Size 


common 


27/06/201310:16 ... 


File folder 




dec 


27/06/201310:06 ... 


File folder 




| exemples 


27/06/201310:06 ... 


File folder 




nclude 


27/06/201310:06 ... 


File folder 




zgoub 


27/06/2013 10:19 ... 


File folder 




zgoubi-5.1,0 


28/07/2013 5:59 PM 


File folder 




pop 


27/06/201310:20 ... 


File folder 




_ AUTHORS 


27/06/201310:06 ... 


File 




*B Command Prompt 


27/06/2013 10:14 ... 


Shortcut 




,_, COPYING 


27/06/201310:06 ... 


File 




J INSTALL 


27/06/201310:06 ... 


File 




Makefile 


27/06/201310:09 ... 


File 




U README 


27/06/201310:06 ... 


File 




TODO 


27/06/201310:06 ... 


File 





□ 



Makefile Date modified: 27/06/2013 10:09 PM 
File Size: 477 bytes 



Date created: 31/07/2009 10:23 PM 



(a) The zgoubi-5.1.0 contents. 



[If ■C:Vzgoubi-5.1.H\Matef le - Notepad-* 




□ I 0 1 £S 1 


File Edit Starch Vie,': Encoding Language Settings 


/lacrc Run P 
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igoubidatlSrr: | ' ' 



1 CFLAG5=-g 
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I FFLAG5=-0 

5 . EOSIX: 



-DGFQRTILAN4 
Wall i-l 



cd ccitjcoti ; i ! HaZZ '■ -Til 
cd zrjQ'jtli ; £ (HAKE | CFEJ 
cd spop ; £ [MAKE ) CFLAG 



m ; 5 (MAKE I 
)i ; 5 (MAKE) 
S (MAKE ) cl 
S (MAKE ) cle 



Male 
/ Male 

/ ;v,, f 



Extended fti, V, \t r Ip, V~) 
■ ; ■ Regular expression 
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■*>■ On losing focus 
Q Always 



(b) Editing 'Makefile'. 
Figure 3: Editing the Zgoubi 'Makefile' to work in Windows. 



can Command Prompt 



it a r 



Microsoft U in do us [Uersion G. 1.7601] 

Copyright Cc> 2 009 Microsoft Corporation . fill rights reserved. 
C: Ssgoubi-5 .1 . 0>nalte 



gure 4: Entering the command 'make' on the Windows command line. 
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• UNIX 

1. If you are unsure if there is a FORTRAN compiler on your sys- 
tem entering the command apropos fortran will show a list of 
the commands available and their use (figure [5]) . If there is no 
installer available it can be obtained using the command sudo 
apt-get install gcc-gfortran, or through the GUI software in- 
staller. 



Mi lucern '3 local host: - _ □ x 


File Edit 


View Search Terminal Help 


lucern -]: 


apropos fortran 




ctags 


(lp] - create a tags file (DEVELOPMENT, FORTRAN) 




fort77 


dp] - FORTRAN compiler (FORTRAN) 




g77 


(1) - GNU project Fortran 77 compiler 




gfortran 


(1) - GNU Fortran compiler 




lucern ~]$ 


1 





Figure 5: Expected response from the apropos command if FORTRAN 
compilers are installed. 



2. Download source file from http : //sourcef orge .net/projects/ 



zgoubi/ (e.g. zgoubi-5.1.0.tar.bz2). 

3. Unpack using the command tar -xjvf zgoubi-5.1.0.tar.bz2 
(figure [6]). 



@ lucern (tilocal host:- 


/Downloads 


_ □ X 


File Edit View Search Terminal Help 


lucern ~/Downloads]i 11 








-rw-rw-r--. 1 lucern lucern 31402Q1 Jul 


1 11:13 zgoubi-5. l.B. tar. bz2 






lucern ~/Downloads]$ tar -xjvf zgoubi-5. 1 


B.tar.bz2 






zgoubi-5 . 1.0/ 








zgoubi -5 . l.S/include/ 








zgoubi-5. l.B/include/OKKP.H 








zgoubi-5 . 1.0/include/MXLD. H 









Figure 6: Unpacking Zgoubi download in Scientific Linux. 



4. Move the unpacked directory 'zgoubi-5. 1.0' to a directory of your 
choice, e.g. usr/local (moved to folder [-J/sw in figure 

5. Within the directory 'zgoubi-5. 1.0' enter the command make (fig- 
ure [7]). 

6. Add the location of the folder 'zgoubi-5. 1.0/zgoubi' to the Path 
- see section fl. 2. 21 



1.2.2 Setting Environmental Variables 

Both MinGW and Zgoubi will need adding to the 'Path' variable. In order 
to do this, follow the instructions for the operating system used. 



• Windows 
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lucern@loealhostWsw/zgoubi-5.1.Q _ □ x 



File Edit View Search Terminal Help 

lucern ~/sw/zgoubi-5. 1 .0] $ 11 
total 88 
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1 
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2 
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1 


11:30 zgoubi 
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Figure 7: Entering the make command in Scientific Linux. 



1. From the Start menu right-click on 'My Computer' or 'Computer' 
and select 'Properties', and 'Advanced System Settings'. 

2. Under the 'Advanced' tab select 'Environmental Variables' (figure 



■ B B | 



GO @i7J^ 



File Edit View Tools Help 
Control Panel Home 
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Remote settings 
# r System protection 

Advanced system settings 
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Tools 
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Settin 
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I I 



L : s=!" v?:':ables for Anet 



Variable 


Value 


Path 


C:VJsers\Anet\AppDat3\Loc3l^nthoug... 


TEMP 


%USERPROFILETn l AppDfltaiocal\Temp 


TMP 


%USERPROFRE%\AppDataiLocal\Temp 



System variables 
Variable 



Value 

WindowsJTT 



C'iProgian - ::■ II T A Corpora.. 



PATH EXT ,COMj.EXE;,BAT;,CMD;.VBSj,VBE;.JSj,., 
PRQCESSOR_A... AMDS1 



| New... ~| | Edit... ~| | Delete ~| 



r 



Figure 8: Setting the Path in Windows 7. 



3. Here there are two boxes, the upper specifying user settings and 
the lower specifying settings for all users. Be careful editing these 
settings as a mistake can affect the correct operation of the com- 
puter. 

4. In the lower box highlight 'Path' and click 'Edit'. 

5. At the end of the existing entry add the address for the MinGW 
bin directory and the Zgoubi directory, e.g. for the base directo- 
ries described in the install above the add to the path ';C:\MinGW\bin' 
and ';C:\zgoubi-5.1.0' (figure 
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Edit System Variable 



L E3 - 



Variable name: 
Variable value: 



Path 



; C : \MinG W Ibin; C : \zgoubi -5,1.0 

OK Cancel 



Figure 9: Inputing the path addresses. 



UNIX 

1. Edit the startup file and modify the PATH variable to include the 
location of the file /zgoubi-5.1.0/zgoubi as follows (e.g. if this file 
is in the directory usr /local/); 

— bash shell 

(a) edit the FT/ .bashrc' file with the folowing; 

(b) PATH="$PATH":/usr/local/zgoubi-5.1.0/zgoubi 

(c) export PATH 

- C shell 

(a) edit the .cshrc' file with the following; 

(b) set path="$PATH":/usr/local/zgoubi-5.1.0/zgoubi 

2. Save and close the file. 

3. To use the graphics program 'zpop' another line can be added to 
the file using the location of the file '/zgoubi-5.1.0/zpop' in the 
same manner as above (inserted before the 'export PATH' line 



for the bash shell) as can be seen in figure 10b below 



1.2.3 Hints 

Depending on your familiarity with Windows the following information may 
be unnecessary. 

• You will need a text editor to edit FORTRAN files. 'Notepad++' 
( |http : //notepad-plus-plus . org/[ ) is freely available and an easy to 
use option for Windows. 

• In order to quickly open the command prompt in the correct folder 
on each use, paste a shortcut to the cmd.exe into the example folder, 
right click and under 'Properties', in the 'Start in' field copy and paste 
the address of the folder containing the zgoubi.dat file. 
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File Edit View Search Terminal Help 

lucern -]s gedit .bashrc 



(a) Opening the bash shell script in the home directory with text editor 'gedit' 



.bashrc 



# .bashrc 

# Source global definitions 
if [ -f /etc/bashrc ] ; then 

. /etc/bashrc 

fi 

# Software directory definitions 
GNAME="SW" 

if [ $GNAME = "" ] 
then 

GNAME=sw 

fi 

export SWDIFt=$HOME/$GNAME 

# set path for zgoubi and zpop| 
PATH="$PATH" : $SWDIFt/zgoubi-5 . 1 . S/zgoubi 
PATH="$PATH" : $SWDIR/zgoubi-5 . 1 . S/zpop 
export PATH 



Plain Text v Tab Width: B v Ln IB, Col 31 



□ 



INS 



(b) The completed shell script. 
Figure 10: Editing the shell script in Scientific Linux. 



1.3 Running Zgoubi 

In Windows the program is run from the command line (cmd.exe). In both 
Windows and Linux, at the command line within the folder containing the 



zgoubi.dat file to be used, type zgoubi and enter (see figure 11). 

A successful run will output a list of elements as specified in the .dat file 
and produce a results file, 'zgoubi.res' alongside other files such as; 

• zgoubi. fai - particle coordinates and spin information. This stores data 
at the end of each magnet - it is useful for analysing phase space. 

• zgoubi. spn - spin coordinate information. 

• zgoubi. pit - particle coordinates and fields experienced by the particles 
stepwise along the beamline. This stores data points within a magnetic 
field only, drift spaces don't store tracking data in this file. 

• zgoubi. map - 2-D field map information. 
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|gj Command Prompt 




1 = 1© |— S 


1 


licrasoft U in do us lUersion 6 


1.7601] 






Copyright <c> 20B9 Microsoft 


Corporation. All rights 


reserved. 




1 ^NUsersSflnetSDesIttopSZgoLibi 


thingsNEMMA >zgoubi 


1 


1 Zgoubi. version 5.1.0. 






Job started on 18-Jul-13, at 10:44:59 






Copying zgoubi. dat into 


zgoubi. res. 






numbering and labe ling 








1/ 16 OBJET /l 


/ 






2/ 16 PARTICUL/2 


/ 






3/ 16 DRIFT /Id 


/3 






4/ 16 CHANGREF/4 


/ 






5/ 16 CHANGREF/5 


/ 






6/ 16 QUflDRUPO/defoc 


/6 






7/ 16 CHANGREF/7 


/ 






8/ 16 DRIFT /sd 


/8 






9/ 16 CHANGREF/9 


/ 






10/ 16 QUADRUPO/foc 


/IB 






11/ 16 CHANGREF/11 


/ 






12/ 16 DRIFT /Id 


/12 






13/ 16 MARKER /bpn Str 


/13 






14/ 16 FA I STORE/14 


/ 






15/ 16 RERELOTE/15 


/ 






Zgoubi, version 5.1.0. 








Job started on 18Jul-13, at 10:44:59 






Job ended on 18-Jul-13, 


at 10:45:02 






CPU time, total : 2.0748130000000002 






3:\Users\Anet\Des]ttop\Zgoubi 


tliings\EMMA>_ 













Figure 11: Running Zgoubi in Windows. 



The results output overview of Zgoubi is written to the zgoubi. res file. 
The particle tracking and field data are stored to the other output files. 
The data can be visualised using the Zpop code for users with access to an 
xterm window. Otherwise extracting the required data can be done using 
other program interfaces. Dr Kai Hock has written MATLAB scripts to 
perform this function (see section 4.1). There are also add-on scripts such 
as PyZgoubi which uses a python interface to input lattice data and analyse 
the results (see section 1.6). 

Further information about the Zgoubi output files can be found in Part 
D of the Zgoubi User's Guide. 



1.4 Running zpop 

The Zgoubi code comes with a graphics package called zpop. It can only be 
run in an xterm window which can be accessed on most UNIX systems with 



the command xterm. An example of use can be seen in section 3.2.1 



1.5 How to use the Zgoubi User's Guide 

The Zgoubi User's Guide is split into four sections. The first section, Part A 
- 'Description of software contents', provides information about the physics 
processes considered, the procedures available and the mathematical meth- 
ods used to perform the integrations. The section begins with a glossary 
of the keywords used in the program. The keywords are how the user de- 
fines the accelerator lattice in the input zgoubi.dat file. Further information 
about the keywords can be found in section 4 of Part A, with details about 
how to use the keywords to be found in section B. 
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Part B - 'Keywords and input data formatting' details all the keywords 
used in the program. To enter lattice information into the zgoubi.dat file a 
keyword is used, followed by further numerical or text data to define the use 
of the keyword. As a simple example a drift section is defined in zgoubi.dat 
with the keyword 'DRIFT' with the length of the section (in cm). A few 
other examples will be discussed in section [2] of this guide. 

In the introduction to Part B a description is given of how to input the 
information given for each keyword. An important thing to note is the units 
expected for each keyword. As an example, both radians and degrees are 
used at different occasions. When defining a lattice careful reference to the 
use of the keywords as defined in this section is strongly recommended. The 
allowed values for each keyword and the units to be used can be found in 
part B. 

In Part C - 'Examples of input data files and output result files' several 
zgoubi.dat files are given as examples of different accelerator definitions. 
The resultant zgoubi.res files are also shown. 

The information regarding instillation and running of Zgoubi is contained 
within Part D - 'Running Zgoubi and its post-processor/graphic interface 
zpop'. 

1.6 PyZgoubi - a python interface to Zgoubi 

Py Zgoubi is a freely available interface to Zgoubi written in python (http: 
//www.hep.manchester .ac.uk/u/sam/pyzgoubi/). It has been designed 
to make reading and writing input data files easier, and takes advantage of 
python's utilities and analysis tools to interpret the output (§]. It requires an 
installation of python with the packages of NumPy, SciPy and Matplotlib. 
It is also possible to install Zgoubi from the PyZgoubi installation if the OS 
has the GFortran compiler installed. 

1.6.1 Installing PyZgoubi on Windows 

Python can be installed on Windows with the required packages and li- 
braries, NumPy, SciPy, Matplotlib either as individual modules ( see http: 
/ /www . scipy . org/ ) or through the single package options such as Anaconda 
(http://continuum.io/downloads) or Enthought Canopy (https : //www. 
enthought.com/products/epd/free/). The 32 bit version is free to all 
users. Links to these products and more are available on the PyZgoubi home- 
page above. The environmental variables need be amended to include the ex- 
ecutable 'python.exe' and also the library site packages, which may have an 
address such as 'C: \Users\Username\AppData\Local\Enthought\Canopy32 
\User\Lib\site-packages'. 

After installing a python package with the above libraries PyZgoubi 
can be downloaded from sourceforge via the homepage (http://www.hep. 
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manchester.ac.uk/u/sam/pyzgoubi/). After downloading it can be un- 



packed to a directory such as 'C:\pyzgoubi' through a MinGW (see 1.2.1 for 
MinGW information) interface opened in the directory containing the tar.gz 
file (for example 'filename. tar.gz') using the following command; 



tar -zxvf f ilename . tar . gz 

After unpacking PyZgoubi, through a command prompt open in the 
pyzgoubi folder enter the command python setup. py install, or to install 
to a specific destination (e.g. /python/install/) with the command python 
setup. py install — prefix=~ /python/install/. The installation dialogue 
will offer suggestions of amendments to be added to the environmental Path 
variable which should be updated accordingly, along with the address of the 



PyZgoubi executable (see section 1.2.2) 



Depending on the installation some small amendments may be necessary 
to run PyZgoubi. A batch file in the pyzgoubi folder (titled for example 
'pyzgoubi.bat') can help pyzgoubi to locate the python.exe executable. An 
example is shown below for an Enthought installation of python. 



@echo off 

python C : \Users\Username\AppData\Local\ Enthought \Canopy32\User\ 
Script s \pyzgoubi %1 

In the python file 'core.py' within the 'run(... )' loop a temporary 
directory is made with a prefix. This can cause problems in Windows which 
can be patched by changing the definition of 'tmpdir = tempfile.mdktemp(... 
)' in this loop to 'tmpdir = tempfile.mkdtempQ'. On some systems the 
'settings.ini' file in the .pyzgoubi folder may need to be edited to ensure the 
path names are correct. 



1.6.2 Installing PyZgoubi on UNIX 

The PyZgoubi homepage contains links and information about how to in- 
stall the code. The required packages of SciPy, NumPy and Matplotlib can 
be installed through Anaconda (link from the homepage) or other sources. 
Anaconda will also suggest appropriate changes to the PATH variable or 
offer to adjust the shell script automatically. 

After a successful installation of python with these libraries on a system 
with a g77 compiler it should now be possible to download and install PyZ- 
goubi following the advice on the homepage and in the README included 
with the source code. The shell environment needs to be configured to in- 
clude the paths for the python executable and paths for the python libraries 
(PYTHONPATH) as advised during the installation procedure. 
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2 Defining a lattice 



To define an accelerator lattice for Zgoubi the details need to be saved into a 
text file named 'zgoubi.dat'. Keeping this input file for different accelerators 
in separate directories is essential to avoid accidentally overwriting one with 
another. In the file each element of the accelerator is specified in turn. 



2.1 Coordinates 



It is important to note that Zgoubi always works in local coordinates, not 
global coordinates. A right-handed system is used but the terminology may 
be slightly different to other commonly used systems, most notably in that 
the x axis is along the general direction of motion. The x axis is zeroed at 



the beginning of a component. In the figure below (see figure 12) the origin 
is in the median plane on a reference curve which coincides with the optical 
axis of optical elements. 



Reference frame and coordinates (V, T, Z, I') in zgoubi. 

OX : in the direction of motion, 

OY : normal to OX, 

OZ : orthogonal to the (X, Y) plane, 

IV : projection of the velocity, v : in the (X, Y) plane, 

T = angle between W and the X -axis, 

P = angle between W and ff. 



Figure 12: The Zgoubi coordinate reference frame. Taken from |2] 
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2.2 Keywords and labels 



In the zgoubi.dat file a keyword is used (in capitals and in quotes) to input 
data about every step of the lattice. The keyword and the data following it 
is read into the Zgoubi program. Each keyword can have two 'labels' on the 
same line. 

' KEYWORD ' labell label2 

Although this label can be free text and used as an aide memoir, it can 
also on occasion be used to produce a result. For the keyword 'MARKER', 
if the second label is .pit the current coordinates will be stored to the file 
named 'zgoubi. pit'. This file can be used with Zpop to produce plots. As 
another example, if given the name of a label the keyword 'FAISTORE' 
will create a '.fai' file for storage of particle data at any element where the 
label is used. An example is given below. Here the output file will be called 
'zgoubi. fai' and will store data at the exit of any element labelled labell. 

' FAISTORE ' 
zgoubi. fai labell 

The details about the available keywords and how to use them can be 
found in Part B of the Zgoubi User's Manual. Further information and 
examples of use can also be found in the Zgoubi Tutorial [9] available online. 



2.3 Handling rotations and translations 

A translation and/or rotation may be required between different elements 
which can be achieved by using the 'CHANGREF' keyword. The CHANGREF 
keyword is used to define transverse and longitudinal shifts and a z-axis ro- 
tation. The entry for this keyword in Part B of the Zgoubi User's Guide is 
shown in figure 13 below. 



CHANGREF Transformation lo a new reference frame 

"Old Style" (Figure below) : 

XCE. YCE, ALE Longitudinal and transverse shifts. 2*cm. deg 3*E 

followed by Z-axis rotation 



Figure 13: An excerpt from the Zgoubi User's Guide |2j. 

The above entry gives an explanation of the function of the term, the 
units required (where '2*cm deg' means two separate entries in cm followed 
by one entry in degrees), and each entry to be in real numbers (as indicated 
by '3*E'). As such, a rotation of the frame of reference by 10 degrees with 
respect to the z axis of the original frame would be entered into zgoubi.dat 
as below. 



15 



' CHANGREF ' 
0 0 -10 



2.4 Defining initial particle coordinates 

The keyword for the initial particle is 'OBJET'. The input parameters are 
specified over the subsequent five lines of code as can be seen in the example 
code below. With reference to Part B of the User's Guide it can be found 
that the number on the second of these lines (with value '2' in the code 
below) selects options about the subsequent variables. It is again important 
to note the units used (1 G = 1CT 4 T). The units for the particle coordinates 
can be in different units dependent on the number option used on line 2. 



' OBJET ' 






-36.689 


♦Rigidity - note the units of kG . cm : 10. 


5 eV electron 


2 


♦Selects menu option 2 




1 1 


♦Total no. of particles, no. of distinct 


momenta 


-0.9 45 


0.0010.011 e ♦y,y',z,z',dl 


, p/p_0 


1 


♦Switch to toggle ray-tracing or not 





This defined object describes the starting coordinates at the beginning 
of a cell in the lattice. If these coordinates were all set to zero the particle 
would travel along the reference path. However this may not be the best 
starting path, and may result in the particle getting lost after travelling 
though a few components. Some trial and error is likely to be involved to 
check if a particle can travel through the lattice correctly. Careful selection 
of a starting point for a cell - often at a point of symmetry - may mean 
that the right starting coordinates can be found by varying the horizontal 
displacement (the Y value) alone. 

2.5 Extracting local particle coordinates 

Printing out the local particle coordinates into zgoubi.res can be done with 
the keyword 'FAISCEAU'. However if the coordinates are to be stored (ie 
saved to file for later analysis) the keyword 'FAISTORE' should be used. 
This saves the particle data to a filename (filename. fai) to be specified under 
the keyword. The keyword 'MARKER' can be used to free-text name a point 
in the lattice. For example the following code would label a point in the 
lattice as three and produce a .fai file 'three_zgoubi.fai' which would record 
the particle data at every occurrence of the marker 'three'. 

'MARKER' three 
' FAISTORE ' 

three_zgoubi . f ai three 

2 ♦This value indicates how frequently the data is 

recorded, i.e. every second lap around the ring 
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3 Example: The EMMA lattice 



EMMA (Electron Model of Many Applications) is a non-scaling FFAG accel- 
erator. It consists of 42 doublet quadrupole cells (see figure 14) in a 16.6 m 
circumference ring which accelerate electrons from 10 — 20 MeV (kinetic en- 
ergy) [To]. 





(b) A photograph of the cell. 



Figure 14: The EMMA quadrupole cell 11 . 



As the EMMA ring contains 42 replications of the same doublet cell 
the lattice definition is comparatively straightforward (see figure 15) - after 



definition the cell can be repeated 42 times to produce the complete ring. 
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Figure 15: The complete 
EMMA ring [11]. Each blue 
and red module is the focus- 
ing/defocusing quadrupole 
doublet, separated from the 
next doublet by an RF cavity. 
There are no dipoles used. 




3.1 The zgoubi.dat file 

The 'zgoubi.dat' input file for the 
EMMA lattice can be seen in fig- 
This section will explain the 
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ure 

content of this file line by line us- 
ing some of the components as de- 
scribed in the previous section. 

Along the right hand side of the 
data in this file it can be seen that 
each keyword has been labelled in 
numerical order. This is not an es- 
sential part of the file, but can make 
matching the keyword to the out- 
put in the zgoubi.res file more sim- 
ple 



■OB JET 1 

-36.6S91S6263712 
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0.510998921 
■DRIFT" Id 
10.5 

■CHAHGREF" 

0 0 -8.571428571429 
' CHANCRE F 1 
0 3.4048 0 

■ QUABRUPO' defoc 
2 

7.5699 5.3 2.5248727452 
0 0 

0 0 0 0 0 0 0 
0 0 

0 0 0 0 0 0 0 
#38 I 38 I 38 

0 0 0 0 

1 CHANG-RE F 1 
0 -3.4048 0 

■ DRIFT 1 3d 



. Sj21"65Se-l:' 1 . 15 1- S52 1 = 1 le-S j j 



It can be seen in figure 
that the results file zgoubi.res num- 
bers each lattice element (the num- 
ber before the keyword). Labelling 
each element in the input file with 
the corresponding number can make 
it easier to locate an input element 
with its output. For this lattice, 
with only 16 keywords used, it is 
not very difficult to identify each 
element in the zgoubi.res file and 
match it to the corresponding ele- 
ment in the zgoubi.dat file but in 
more complicated lattices this is less 
straightforward. 

Line 1 of the zgoubi.dat file is 
for free text, in order to identify the 
lattice. The first keywords needed 

for this, and most lattices, are 'OB JET' and TARTICUL'. OB JET defines 
the object, i.e. the initial particle coordinates and PARTICUL defines the 



29 'CHAHGREF' 

30 0 0.7514 0 

31 ■QUADRUPO' foe 

32 2 

35 S.8782 3.7 -2 . 2290516874 

34 0 0 

35 0000000 

36 0 0 

37 0000000 

38 #29|29|29 

39 0 0 0 0 

40 'CHAHGREF' 

41 0 -0.7514 0 

42 'DRIFT' Id 
45 10.5 

44 "MARKER ' bpm_Str 

4 5 1 FAI STORE ' 

'- f zgcrjfci . f bpir. 3tr 

47 0 

48 1 REBEIwOTE ' 



Figure 16: The zgoubi.dat file for the 
EMMA lattice. 
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53 
54 
55 
56 
57 
58 
59 
60 



of 



Numbering! 
lattice 

component in 
zgoubi 



res 



MAGNETIC RIGIDITY 



-3 6. 65 9 3tG*cm 



Free text from 



OB JET 1.2) 

zgoubi.dat 



calcul L'ZS r;.i.rE-:rc:?.j3 



FORME DE 



Figure 17: Except from zgoubi. res regarding keyword 'OBJET'. 



characteristics of the particles in the beam. For EMMA the beam consists of 
electrons. The zgoubi. res file output gives further details about the particle 
from the input data from OBJET and PARTICUL (see figure 18). It is 



strongly advised to check this file after defining a lattice to ensure this 
output is correct, and the data has been input correctly. 



62 
63 
64 
65 
66 
67 
68 
69 
70 
71 
72 
73 
74 
75 
76 
77 
78 
79 
80 
81 



PARTICUL 



Farticle properties 



Ma 33 

Charge 

G factor 



0.510999 
-1.602177E-19 
1.159652E-03 



Reference data : 

rigidity (kG.cir.) 
mass (MeV/c2) 
rr.orr.enfjur. (MeY/c) 
energy, total (MeV)- 
energy, kinetic (MeV) 
beta = v/c 
garnr.e 

ceta^canrra 



MeV/c2 
C 



T. r. T. T. T. T. T. T. 



it * rr * * >r * * * * * :r * rr * ' * >r * * 



-36.6892 
0.510999 

10.9991 

1 1 . :■ 1 1 :■ 

10.5000 
0.9989225664 

21.54798925 

21 .52477272 



Figure 18: Except from zgoubi. res regarding keyword 'PARTICUL' 



At this point in the input file the cell can be defined. In EMMA the cell 
consists of the quadrupole doublet followed by a drift of 21 cm. The next 
cell is then at an angle to the first. As there are 42 cells in the complete ring 
this angle is 360°/42 = 8.57° (actually —8.57° with respect to the x axis 
to describe a rotation towards the centre of the ring) . For this lattice the 
drift section has been described as two 10.5 cm sections at the beginning and 
end of the cell. This means the rotation of reference frame appears within 
the cell description rather than at the end as expected. The reason for this 
relates to the initial injection of particles in the OBJET definition. In order 
to obtain a stable orbit around the ring some trial and error with the initial 
particle coordinates is required. Using the middle of the drift space as the 
start of the cell allows a stable orbit to be found by varying the horizontal 
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displacement (Y) alone. If the start /end of the cell involved the rotation the 
angle theta (T) would need to be varied too, making the process of finding 
a stable orbit more complicated. So it can be seen in figure 16 at line 10 the 
first drift section of 10.5 cm is defined, which is then followed by a change 
in reference frame of a rotation of —8.57°. The other half of the drift cavity 
is defined at the end of the cell on line 42. This defines a cell represented 



by the schematic picture in figure 19 




Figure 19: Schematic drawing of the cell as defined in zgoubi.dat. 



The CHANGREF on line 12 of zgoubi.dat rotates the coordinate system 
from 'a' in figure 19 to one with the x-axis parallel to 'b'. The following 
CHANGREF on line 14 then performs a translation to move the coordinates 
to 'b', with the x-axis in line with the centre of the defocusing quadrupole. 
Line 16 then defines the defocusing quadrupole, with the label 'defoc' and 
is followed by a CHANGREF which reverses the previous translation and 
moves the coordinates to 'c'. After a further drift section there is another 
change of coordinates to 'd' before the definition of the focusing quadrupole 
on line 31. One final CHANGREF moves the coordinates to 'e' before the 
final drift section is defined at line 42. 

The defocusing and focusing quadrupoles are defined at lines 16 and 31 
respectively. The initial value of '2' is an instruction to print the field and 
coordinates along the trajectories. The following lines (18 and 33) define the 
length, radius and magnetic field at the pole tip for each quadrupole. The 
focusing magnet can be seen to have a negative value for this field. Both 
quadrupoles are then defined with four lines consisting of zero values. These 
lines can be used to define the fringe magnetic fields - the 'entrance' and 'exit' 
fringe fields. With zero values a 'sharp edge' magnetic field approximation 
is used. 

On lines 23 and 38 three values are entered to define the 'XPAS' - this 
defines the number of steps for the integration process in the entrance field, 
main field and exit field of each component. If passed a single value a step 
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length in cm would be used. 

At line 44 a marker is placed. This itself has no impact on the beam (if 
given a second keyword of .pit data from this point in the lattice will be 
stored in the zgoubi.plt file) but marks the position on the lattice with the 
label bpm_str. The following keyword 'FAISTORE' stores particle infor- 
mation in a .fai file given as an argument, here zgoubi.fai. The information 
is stored at every occurence of the labels given on line 46 which in this case 
is bpm_str. So the net result of lines 44-47 is to produce a file output of 
particle data at the end of the cell where the marker is placed. 

The 'REBLOTTE' keyword on line 48 of figure 16 is a command to re- 
peat the zgoubi.dat file. Here it is given the values '42 0 99' which translates 
as 42 repetitions (i.e. one complete ring) with the '0' specifying a level of 
verbosity in the .res file and the '99' indicating that the particle coordinates 
at the end of one pass are used as initial coordinates for the next pass. To 
track the particle through several laps of the ring a multiple of 42 would be 
used for the first value. 



3.2 Running EMMA and sample output 

A run can be performed by typing the command zgoubi in the directory con- 
taining EMMA's zgoubi.dat file (within a command prompt in Windows); 



this can be seen in figure 20, the run produces four output files. 



3.2.1 Zpop output 

If used in UNIX the output can be visualised with Zpop which is part of the 
Zgoubi package. In the following example the same zgoubi.dat file is used 



as input as seen in figure 16 



In order to produce data plots first Zgoubi should be run as in the 
previous section to produce .fai and/or .pit files, as can be seen in figure 



21a An xterm window can then be opened with the command 'xterm'. In 



the xterm window the command zpop (see figure 21b) then opens the menu 



21c and a blank tektronix window. Firstly option 1, 'Run Zgoubi' should 
be selected in the xterm window to produce a zpop. log file. After this has 
been done the other options can be selected to examine different data. A 



list of the available variables to plot can be seen in figure 22 There is also 



an analysis package as part of Zpop accessible through option 8 of the main 



menu. This offers options as can be seen in figure 23 below. 

As an example of the possible options, it is possible to plot the track 
of the particle through the lattice quadrupole by loading the zgoubi.plt file 



(see figure 24 ) . Plotting the lab X and Y coordinates then produces a plot 
showing one cell in the lab coordinates. The quadrupoles can be seen as 
trapezoidal rather than rectangular shapes as the axis have different scales. 
The reference track which passes through the centre of the quadrupoles can 
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IMS 



:i:\Users\flnet\Desktop\Zgoubi tbings\EMMA >di: 
Uolume in drive C is OS 
volume Serial Number is 082D-47FD 

Directory of C :\Users\Anet\Desktop\Zt[oubi 



sVEMMA 



| 24/07/2013 
24/07/2013 
23/07/2013 
L8/07/2013 



01:16 PH 

01:16 PM 

02:56 PM 

04=10 PH 
2 FileCs 
2 Dir<s> 



<DIB> 
<DIB> 

1,498 Cnnnand Prompt. Ink 
2,518 zgoubi.dat 
4.016 bytes 
208,422,203,392 bytes free 



tSDesktopSZgoubi things\EMMA >zgoubi 
13:16:10 



Zgoubi, version 5.1.0. 

Job started on 24-Jul-13, 
Copying zgoubi.dat into zgoubi 
numbering and labeling element; 



1/ 


16 


OB JET /l 


/ 


2/ 


16 


PARTICUL/2 


/ 


3/ 


16 


DRIFT /Id 


/3 


4/ 


16 


CHANGREF/4 


/ 


5/ 


16 


CHANGREF/5 


/ 


6/ 


16 


QUADRUPO/defoc 


/6 


7/ 


16 


CHANGREF/7 


/ 


8/ 


16 


DRIFT /sd 


/8 


9/ 


16 


CHANGREF/9 


/ 


10/ 


16 


QUADRUPO/foc 


/10 


11/ 


16 


CHANGREF/11 


/ 


12/ 


16 


DRIFT /Id 


/12 


13/ 


16 


MARKER /bpm Str 


/13 


14/ 


16 


FflISTORE/14 


/ 


15/ 


16 


BEBELOTE/15 


/ 






rsion 5.1.0. 





^:\Usei's\flnet\Desktop\Zgoubi tbings\EMMA Mir 
Uolume in drive C is OS 
Uolume Serial Number is 082D-47FD 

Directory of C:\Users\Anet\Desktop\Zgoubi thingsVEMMA 



24/07/2013 
24/07/2013 
23/07/2013 
18/07/2013 
24/07/2013 
24/07/2013 
24/07/2013 
24/07/2013 



01:16 PM 
01:16 PM 
02:56 PM 
04:10 PM 
01=16 PM 
01:16 PM 
01:16 PM 
01:16 PM 



1,498 Conmai 
2,518 zgoub 
22,168 zgoub 



d Prompt . Ink 

.dat 

.fai 



Figure 20: A run of Zgoubi in a Windows command prompt showing the 
directory contents before and after the run. 



be seen changing direction in line with the 'CHANGREF' commands from 
zgoubi.dat. The particle tracking data can be seen as two arcs of data 
through the quadrupoles. The trapezoids representing the quadrupoles do 
not define the physical extent of the magnetic field, so it can be seen that 
although the particle track happens outside of the defocusing quadrupole 
trapezoid the track is still curved by its magnetic field. 

The zgoubi. fai file is useful for analysing the phase space. From the 
Zpop main menu choosing the menu options to open the file 'zgoubi. fai' 
allows plotting of a choice of variables. If the variables Z and Z' are chosen 
(see figure 21d) and then plotted the following phase space chart can be 
produced (see figure 25b). 



3.2.2 Analysis in Windows 

As the running of Zpop requires an xterm window it it not ideally suited 
to a Windows system. In this situation a MATLAB script can be used to 
extract the data from the zgoubi. fai or zgoubi. pit file (see Appendix 4.1). 



The output from these files can be seen in figure 26 
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lucern@localhostWDarWork 



File Edit View Search Terminal Help 

lucern ~/DarWork]$ 11 

total 8 

drwxrwxr-x. 2 lucern lucern 4096 Jul 22 09:41 prewiousRun 
-rw-rw-r--. 1 lucern lucern 2611 Jul 1 14:25 zgoubi.dat 
lucern ~/DarWork]$ zgoubi 

Zgoubi, version 5.1.9. 

Job started on 22- Jul- 13, at 39:41:44 
Copying zgoubi.dat into zgoubi . res , 
numbering and labeling elements. . . 



15/ 16 REBELOTE/15 



Zgoubi, version 5.1.0. 

lob started on 22-JUI-13, at 39:41:44 
Job ended on 22-Jul-13, at 89:41:48 

CPU time, total : 4.4803189999999997 
lucern -/DarWork]$ 11 
total 20068 

2 lucern lucern 

1 lucern lucern 

1 lucern lucern 

1 lucern lucern 



4396 Jul 22 

2611 Jul 1 

216624 Jul 22 

0 Jul 22 

1 lucern lucern 202O6640 Jul 22 

1 lucern lucern 114614 Jul 22 



drwxrwxr-x 
-rw-rw-r- 

- rw- rw- r- - 
-rw-rw-r-- 

- rw- rw- r- - 

- rw- rw- r- - 
lucern ~/DarWork]S xterm 



09:41 previousRun 

14:25 zgoubi.dat 

09:41 zgoubi. fai 

09:41 zgoubi.log 

09:41 zgoubi. pit 

09:41 zgoubi. res 



(a) A run of zgoubi.dat. 




lucern@localhost:-/DarWork 



RUN ZGOUBI 

Menu For direct plots from 

} plt. 4 fai, t spn type zgoubi output tiles 



Menu for c 
Exit zpop 



■ther- final ysis/Flafc 



(b) Entering the command zpop in the 
initial xterm window. 



(c) The initial Zpop menu in the xterm 
window. 



I u cern @l ocal h as t: ~ /Oar Work 



********* 



********* 



MENU - Graphic processing : 



GPEN FILE - current is zgoubi .fai 

VARIABLES TU PLOT 

PRESENT: H-AXIS : Z (KX= 4) 
V-AXIS : V (KY= 5) 

PLOT OPTIONS 
MANUAL SCALES 
AUTOMATIC SCALES 
** PLOT Y V.S. X ** 
Save graphic screen 
EXIT THIS MENU W 
ERASE DISPLAY ft 
KILL/CREATE GRAPHIC SUB-PROCESS 
Superpose a curve 



4 

5 

7 

8 

9 
12 
15 
20 

88 HELP 

************ 



********* 



Option number : 



(d) The menu ready to plot Z vs Z' in the xterm window. 
Figure 21: Output from Zgoubi on a Scientific Linux OS. 
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I u ce r n @l o c a I h o st : -/Da rW ork 




; Available variables - 



!« (Hoi 



z.), KY (Vert.) ; 



CURRENT COORDINATES ; 

1, 2, 3, 4, 5, G, 7, 8: dp/p, Y, T, Z, P, S, 
m rd m rd m 
* Note : Y, K are in optical element frame. 

In polar frames, Y=Radius and X=Angle 



Step size (cm) 
r = sqrt(y"2+z"2) 
Kinetic E (MeV) - 



Jith .pit type files 
dith .fai type files 



INITIAL COORDINATES ; 

11,12,13,14,15,16,17 : dp/p, Y, T, Z, P, S, 
m rd m rd m 

SYNCHROTRON NOTION: 

18, IS : phi-phi_s (rad), dp/p 

SPIN: 



tine, J! 
mu-s pi 



1 1 

mu-s 



21,22,23,24: 
25,26,27,: 



HISTOGRAM : 

28: Counts 



Sx, Sy, Sz, <S> 

SuroSx/#turn, SumSy/#turn SumSz/#turn 



E and S FIELDS : 

30,31,32,33 : 
34,35,36,37 



Dx, By, Bz, sqrt(By"2+Bz"2) (T) 
Ex, Ey, Ez, sqrt(Ey"2+Ez"2) (eV/m) 



COORJINATES IN LABORATORY: 

42,44,40: Y_Lab, Z_Lob, 



S_lost (in) : 

IPASS 

NOEL 



Distance where particle is lost 
Pass (or Turn) # 
Element # 



* Give desired variables (KK=KY to quit) 



Figure 22: The variables available to plot within Zpop for the zgoubi.fai file. 



I u cern @l ocal h ost: -/DarWork 



MENU - Analysis/Graphic 



1 


Open file - current is zgoubi.fai 


3 


Plot options 


4 


Manual scales 


6 


Synoptic 


8 


Save graphic screen 


9 


Exit this menu 


10 


SR loss parameters 


11 


Isofield lines from a map 


12 


Erase display 


13 


Fourier spectrum - multiturn 


14 


Ellipse fit - multiturn or multiparticle 


15 


Kill/create graphic sub-process 


16 


Synchrotron radiation distributions 


17 


Mean orbit - multiturn c.o., or multiparticle 


18 


Fringe field matching 


19 


Transverse beam density matching 


20 


Superpose a curve 


88 


HELP 




Figure 23: The analysis menu in zpop. 
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lucern@localhost:~,DarWork 



MENU - Graphic processing J 



1 OPEN FILE - current is igoubi.pl t 

2 VARIABLES TO PLOT 

PRESENT; H-AXIS ; X_Lab (KX=48) 
V-AXIS : Y_Lab (KY=42) 

3 PLOT OPTIONS 

4 MANUAL SCALES 

5 AUTOMATIC SCALES 

7 ** PLOT T V.S. X ** 

8 Save graphic screen 

9 EXIT THIS MENU 
12 ERASE DISPLAY 

15 KILL/CREATE GRAPHIC SUB-PRUCESS 

20 Superpose a curve 

88 HELP 



: Option number I 



(a) The menu showing the selected options for the plot below using the zgoubi.plt 
file. 



mi vs. X_Lab (mi 




Mi-ma H/V: -7.825E-03 0.399 / -5.401E-02 7.430E-02 

Psrt# 1- 40000 <-i ; Lmnttt 1; psss* 1- 421; point 



(b) A plot to show the particle track (in lab coordinates) through the magnetic 
fields of the quadrupoles of one cell. The .pit file only contains tracking data 
though magnetic fields. 



Figure 24: An example of using zgoubi.plt in zpop. 
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lucern@localhost:-/DarWork 



File header : 
COORDINATES - STORAGE FILE, 22-Jul-13 03:41:44 
emma 



Z' (rad) vs. Z Cm) 
min.-max. Hor,; -1.G5845570E-05 1.65361972E-05 
Ver.; -1.40848881E-04 1.40268925E-04 
(min+max)/2 Hor, S, ver.: -2.41798878E-08 -2.89977783E-07 (ra) / (rad) 
-2.41798878E-06 -2.89977783E-04 (zgoubi units) 
Part* 1- 40000 (*) ; Lmnt# 1; pass* 1- 421; 420 points 



SUM(T)dX [XMI->XHA] = 0.00000000E+00 
PLOTTED 420 POINTS, OVER 



420 READ IN FILE 



Means : <X>, SigmaX, <Y>, SigmaY, Correlation 
-1.882736E-09 1.141023E-05 8.423373E-09 9.660740E-05 0.817335 
Linear regression : Y = 2.14522018E-08 + 6.92015691E+00 * X 

3*2-D domains, centered, with emittances : 

Eps_y/pi = 2.0938E-07 * 1,00 m.rad 

Eps_z/pi = G.3511E-10 * 1.00 m.rad 

Eps_t/pi = 3.41UE-15 * 1.00 s.eV 

Number of particles within these 3*2-D domains : 0 



MATCHING ELLIPSE ; 

V vs. Z 

Min-max - Hor.: -1.65846E-05 1.65362E-05; Ver.: -1.40849E-04. 1.4026SE-04 
Centering, H/V : 0.279 / 10.5 Jf 
Eps/pi, Deta, Alpha: 6.35UE-10 0.205 -1.42 



( ' Press RETURN for more : ' ) 



(a) The xterm output from plotting Z vs Z' 




Eps/pi. Beta. Alpha; 6.4481E-10 0.205 -1.44 
Mi-ma H/V; -1.S30E-05 1.S48E-05/ -1.389E-04 1.401E-04 
Fart* 1- 40000 <*) ; Lnnta 1; pass* 1- 43; 42 pol 



(b) The graphical output of Z vs Z' in the tektronix window with a 'matched 
ellipse'. 

Figure 25: Output from Zpop on a Scientific Linux OS. 
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File Edit View Insert lools Desktop Window Help 
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Figure 26: Output from MATLAB scripts analysing zgoubi.fai (see 
pendix 4.1) in Windows. 07 



3.2.3 EMMA with PyZgoubi 



The identical lattice can be denned using the PyZgoubi script found in ap- 
pendix [472J A version of this script and other EMMA examples are included 
in the PyZgoubi downloaded package. As with Zgoubi, the program is run 
from a command line (cmd.exe in Windows) open in the directory contain- 
ing the particular script. The 'emma_ellipse.py' script is run by entering the 
command pyzgoubi emma_ellipse.py (see figure 27a). The output of the 
script begins with a print to screen of the zgoubi. res file produced (figure 
27b), followed by other instructions from the code - in this case a list of the 



Z,P values and a graphical output (see figure 27c). 

An advantage of PyZgoubi is the ability to use python analysis tools 
on the resultant data. Included in the PyZgoubi downloaded package are 
sample EMMA scripts to calculate the closed orbits, tune, Twiss profiles 
and magnetic apertures for the lattice. Futher information about the use 



of PyZgoubi can be found at http://www.hep.manchester.ac.Uk/u/sam/ 
pyzgoubi/doc/O . 3/doc . html 



28 



Command Prompt 



C:Spyzgoubi-0 .4.1 . oldSexamples>pyzg"oubi emma_ellipse . py_ 



< L 



(a) Entering the command to run. 



C:SpyE9Oubi-0.4.i.oldSeKainpleB>pj:sgoubi emma_e llipse .pi 
C:\pyzgoubi-0. 4. i .o ldNexampleB >pytlion C:\j3ei-5Sflnet'vflppData'vLocalSEiitliciughtSCaiiopy32SL5ei-SScriptsSpyE! 



- 9. 00000B 000000s -01 4.5000000090006+01 1 . 00 000 00000 00e -03 1 . 0000000 00000 e -02 0.0 00000000 000e +00 1 .000 000 00000 Ben 



le+00 -8.571428571429e+00 



QUflDFUPO' defoc 

.56?9O0B00000e+e0 5. 3 00000000 000e +00 2 .52487275O5B0e+00 




(b) The initial output of the run. 



Figure 1 



> 0020 -0.0015 -0.0010 -0.0005 0.0000 0.0005 0.0010 0.0015 0.0020 

Z(cm) 



too * 



(c) The graphical output of the script. 



Figure 27: Running emma_ellipse.py in Windows. 
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4 Appendix 



4.1 MATLAB scripts 

The following codes were written by Dr. Kai Hock to extract and plot data 
from the Zgoubi output files using MATLAB. 



4.1.1 get_zgoubi_data.m 

This code extracts data from zgoubi. pit. 



function [Y , T, Z, P, X, S, BX , BY, BZ] = get_zgoubi_data ( 

filename ) 
X filename = ' zg oub i . pit ' ; 
X si = ' e ' ; X particle label 

fid = fopen (filename, 'r'); 

f gets (fid) ; 
f get s (fid) ; 
f gets (fid) ; 
fgets(fid) ; 

s = fscanf (fid, ' \'/.s ' , 1) ; 
f gets (fid) ; 

a = fscanf (f id , ' V/.f ' , 3) ; 
f gets (fid) ; 

c = fscanf (fid , 'V/.f ' , 3) ; 
fgets(fid) ; 

b = fscanf (fid , ' V/.f ' , 8) ; 



while feof (fid) 
Y(n) = a(2) 
T(n) = a(3) 
Z(n) = c(l) 
P(n) = c(2) 
S(n) = c(3) 
X(n) = b(5) 
BX(n) = b(6) ; 
BY (n) = b(7) ; 
BZ (n) = b (8) ; 
n = n + 1 ; 

f gets (fid) ; 
fgets(fid) ; 
s = f s canf (fid, 
f gets (fid) ; 



0, 



'V/.s>, 1); 



a = fscanf (fid , ' V/.f ' , 3) ; 
fgets(fid) ; 
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c = f scanf (fid , ' V/.f ' , 3) ; 
f gets (fid) ; 

b = f scanf (fid , ' V/.f ' , 8) ; 
end 

fclose (fid); 



4.1.2 plt_zgoubi_plt_2b.m 

In this script the previous code is called to extract the data which is then 
plotted. 

clear 

filename = ' zgoubi . pit ' ; 

[Y , T, Z, P, X, S, BX , BY, BZ] = get _zgoubi _dat a ( f ilename ) ; 

close all 
f igur e 

subplot (221) , plot(S/100, BZ/10, ».») 
set(gca, 'font size' ,12) 
xlabel ( ' S u (m) ' , 'fontsize', 14) 
ylabel ( ' BZ U (T) ' , 'fontsize', 14) 

subplot (222) , plot(S/100, Y/100, '.') 
set(gca, 'fontsize' ,12) 
XxlabeK'S (m) ' , 'fontsize', 14) 
ylabel (' Y u (m) ' , 'fontsize', 14) 

subplot (223) , plot(S/100, T/1000, '.') 
set(gca, 'fontsize' ,12) 
XxlabeK'S (m) ' , 'fontsize', 14) 
ylabel (' T u (rad) ' , 'fontsize', 14) 

figure 

subplot (221) , plot(S/100, BY/10, '.') 
set(gca, 'fontsize' ,12) 
XxlabeK'S (m) ' , 'fontsize', 14) 
ylabel ( 'BY U (T) ' , 'fontsize', 14) 

subplot (222) , plot(S/100, Z/100, '.') 
set(gca, 'fontsize' ,12) 
xlabel (' S u (m) ' , 'fontsize', 14) 
ylabel (' Z u (m) ' , 'fontsize', 14) 

subplot (223) , plot(S/100, P/1000, '.') 
set(gca, 'fontsize' ,12) 
xlabel (' S u (m) ' , 'fontsize', 14) 
ylabel ( 'P u (rad) ' , 'fontsize', 14) 
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f igure 

plot(Z/100, P/1000, 'o') 

set(gca, 1 f ontsize ' , 20) 

xlabel ( ' Z u (m) ' , 'f ontsize', 24) 

ylableCZ' ' u (rad) ' , 'fontsize', 24) 



4.2 PyZgoubi EMMA script 

This script, emma_ellipse.py, will write the zgoubi.dat file for the EMMA 
lattice, print the 'zgoubi.res' output to screen and plot a chart of Z vs Z' (or 
Z vs P). 



print "running emma example" 
import pylab as pit 
emma = Line ('emma') 

xpas = (20,20,20) 

cells = 42 
angle = -360/cells 
d_offset = 34.048 * mm 
f_offset = 7.514 * mm 

#lengths 

Id = 210 * mm 

sd = 50 * mm 

fq = 58.782 * mm 
dq = 75.699 * mm 

# quad radius 
fr = 37 * mm 
dr = 53 * mm 

fb = -6.02446402 * fr * T 
db = 4.76391085 * dr * T 

ob = DBJET2Q 
emma . add ( ob) 

emma . add (ELECTRON () ) 

emma . add (DRIFT ( ' Id ' , XL=ld*cm_/2) ) 
emma . add (CHANGREF ( ALE = angle) ) 

emma . add (CHANGREF ( YCE = d_of f set * cm.) ) 

emma . add ( QUADRUP0 (' defoc ' , XL=dq*cm_, R_0=dr*cm_, B_0=db* 

kgauss_ , XPAS=xpas , IL=2)) 
emma . add (CHANGREF ( YCE = - d_of f set * cm. ) ) 

emma . add (DRIFT (' sd ' , XL=sd*cm_)) 
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emma . add ( CHANGREF ( YCE = f _of f set * cm_ ) ) 

emma . add ( QUADRUPO ( ' f oc ' , XL=fq*cm_, R_0=fr*cm_, B_0=f b*kgauss_ , 

XPAS = xpas , IL = 2)) 
emma . add (CHANGREF ( YCE = - f _of f set * cm_ ) ) 

emma . add (DRIFT ( ' Id ' , XL=ld*cm_/2) ) 

emma . add (FAISCNL (FNAME= ' zgoubi . f ai ' ) ) 

emma . add (REBELQTE (K=99 , NPASS=42) ) 

emma . add (END () ) 

rigidity = ke_to_rigidity ( 10 . 5e6 , 0 . 5 1 099892 e6 ) 
ob . set (B0R0=- rigidity) 

ob . add(Y=-0.9 , T=45 , Z=0.001, P=0.01, D=l) 

print emma . output ( ) 

res = emma . run () #xterm = True) 

fai_data = res . get_all ( ' f ai ' ) 

print "fai" 

print "PASS Z P" 

z=[] 

q=[] 

for p in fai_data: 

z . append (p [ ' Z ' ] ) 
q . append (p [ ' P ' ] ) 

print p[>PASS>], p['Z'], p['P'] 

fig = plt.figureQ 
pit . plot (z , q, ' r+ ' ) 
fig.suptitle('Z u vs u P') 
pit . xlabel ( ' Z u (m) > ) 
pit . ylabel ( 'P (rad) ' ) 
pit . show ( ) 

print res . res () 
res . clean () 
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